home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 123_01 / dio.doc < prev    next >
Text File  |  1985-03-09  |  11KB  |  443 lines
  1. .bp 1
  2. .in 0
  3. .he 'DIO (3)'03/10/83'DIO (3)'
  4. .fo ''-#-''
  5. .fi
  6. .in 7
  7. .ne 6
  8. .ti -7
  9. NAME
  10. .br
  11. dio - directed I/O for BDS C
  12.  
  13.  
  14. .ne 6
  15. .ti -7
  16. SYNOPSIS
  17.  
  18. .nf
  19. #include bdscio.h
  20. #include dio.h
  21.  
  22. main(argc, argv)
  23. int argc;
  24. char **argv;
  25. {
  26.     /* calls to wildexp() and dioinit() can be reversed. */
  27.  
  28.     _allocp = NULL;        /* initialize storage allocation */
  29.     dioinit(&argc, argv);    /* direct I/O streams (required) */
  30.     wildexp(&argc, &argv);    /* expand wild cards (optional)  */
  31.     main1(argc, argv);    /* do the real work         */
  32.     dioflush();        /* no error if we get here     */
  33. }    
  34. .br
  35. .fi
  36.  
  37.  
  38. .ne 6
  39. .ti -7
  40. DESCRIPTION
  41.  
  42. Dio is a package which, when linked together with a BDS C program,
  43. provides that program with the following unix-like features:
  44.  
  45. .nf
  46. o  I/O redirection on the command line
  47. o  Pipes specified on the command line
  48. o  I/O directed to special files
  49. o  Wildcard expansion of file names (optional)
  50. .br
  51. .fi
  52.  
  53. To use these features a program must follow the synopsis above.
  54.  
  55. The version of DIO described here
  56. is an extension of the original version supplied
  57. with the BDS C compiler.
  58.  
  59.  
  60. .ne 6
  61. .ce
  62. I/O REDIRECTION AND PIPES
  63.  
  64. You may activate redirection and pipes using five special arguments
  65. on the command line:
  66.  
  67. .ne 4
  68. .in +5
  69. .ti -5
  70. >foo
  71. .br
  72. Causes all standard output to go to the file "foo" instead of the console.
  73. In particular, causes putchar() and putc(c, STD_OUT) to go to "foo".
  74.  
  75. .ne 4
  76. .ti -5
  77. +foo
  78. .br
  79. Like >foo except that the characters are ALSO
  80. sent to the console.
  81.  
  82. .ne 4
  83. .ti -5
  84. @foo
  85. .br
  86. Causes all output to the standard error stream
  87. to be sent to foo.
  88. In particular, causes putc(c, STD_ERR) to go to "foo".
  89.  
  90. .ne 4
  91. .ti -5
  92. <foo
  93. .br
  94. Causes all input from the standard input stream to come from file "foo".
  95. In particular,
  96. causes getchar() to return characters from the
  97. file named "foo" instead of from the keyboard.
  98.  
  99. .ne 4
  100. .ti -5
  101. command |prog
  102. .br
  103. Causes the standard output of the command
  104. specified in "command" to be fed into the
  105. standard input of another program, "prog."
  106. (BOTH "command" and "prog" must be compiled
  107. with dio).
  108. Multiple pipes may be chained on one command line.
  109. .br
  110. .in -5
  111.  
  112. Warning: redirection and pipes work only for TEXT.
  113. This mechanism should not be used for binary data.
  114.  
  115. There must never be any spaces between >,+,<,@ or | and the
  116. corresponding filename.
  117.  
  118. When no "<" or "|" operator is used, standard input comes from the
  119. console and all standard line editing characters are recognized.
  120. To indicate end-of-file, you must type
  121. .br
  122. ^Z <CR>  (control-Z followed by    a carriage-return.)
  123.  
  124. When no ">" or "|" operator is used, standard output goes to the
  125. console.
  126.  
  127.  
  128. .ne 6
  129. .ce
  130. SPECIAL FILES
  131.  
  132. Special files are jargon for I/O devices (like printers or consoles)
  133. which appear to a program to be a disk file.
  134. There are two special files, namely PRINTER and TTY.
  135.  
  136. .ne 7
  137. These special files can be named on the command line:
  138.  
  139. .nf
  140.      >printer  sends STD_OUT to the printer.
  141.      @printer  sends ERR_OUT to the printer.
  142.      >tty      sends STD_OUT to the user's console.
  143.      @tty      sends ERR_OUT to the user's console.
  144.      <tty      gets  STD_IN from the user's console.
  145. .br
  146. .fi
  147.  
  148. For obvious reasons, input can not be gotten from the printer.
  149.  
  150. .ne 3
  151. The dio package also provides a way for a program to direct
  152. I/O to a particular device, regardless of the command-line settings.
  153. Input directed from DEV_TTY always comes from the user's console.
  154. Output directed to DEV_TTY always goes to the user's console.
  155. Output directed to DEV_LST always goes to the printer.
  156.  
  157. .ne 3
  158. .nf
  159.      c = getc(DEV_TTY);   ALWAYS gets c from the user's console
  160.      putc(c, DEV_TTY);    ALWAYS prints c on the user's console
  161.      putc(c, DEV_LST);    ALWAYS prints c on the printer
  162. .br
  163. .fi
  164.  
  165.  
  166. .ne 6
  167. .ce
  168. WILDCARDS
  169.  
  170. Wildexp() expands ambiguous file names (afn's) on the command line
  171. into a list of files which match the afn.
  172. Note that wildcard expansion should NOT be used for programs
  173. that use command-line arguments containing '*' or '?' to denote something
  174. besides file names.
  175. Examples would be the translit (tr) search (grep) or change (gres) utilities
  176. which use '*' and '?' in text patterns on the command line.
  177.  
  178. An afn preceded by a "!" causes all names matching the given
  179. afn to be EXCLUDED from the resulting expansion list.
  180.  
  181. When giving a "!" afn, "*" chars in the string matches to the
  182. end of either the filename or extension, just like CP/M,
  183. but "?" chars match ONE and ONLY ONE character in either
  184. the filename or extension.
  185.  
  186.  
  187. .ne 6
  188. .ce
  189. THE DIRECTED I/O LIBRARY
  190.  
  191. The following functions make up the directed I/O library.
  192.  
  193. .in +5
  194. .ne 4
  195. .ti -5
  196. dioinit(&argc, argv)
  197. .br
  198. Make this (or wildexp) the first routine that your main program calls.
  199. Dioinit() reads the command line and redirects I/O if requested.
  200. Any arguments that start with '<' '>' '+' '@' or '|' become invisible
  201. after this call.
  202.  
  203. .ne 4
  204. .ti -5
  205. dioflush()
  206. .br
  207. Flushes and closes all directed output files (if any).
  208. Make sure you call dioflush() whenever you exit the program.
  209. On abnormal termination, call dioflush() before calling exit().
  210.  
  211. .ne 4
  212. .ti -5
  213. getchar()
  214. .br
  215. Gets a character from the console
  216. or from a directed input file (or special file) if one
  217. was specified on the command line.
  218.  
  219. .ne 4
  220. .ti -5
  221. putchar(c)
  222. .br
  223. Puts a character out to the console,
  224. or to a directed output file (or special file) if one
  225. was specified on the command line.
  226.  
  227. .ne 4
  228. .ti -5
  229. putc(c, file)
  230. .br
  231. Puts a character to a file (or special file).
  232. This routine was not included in the old dio package.
  233.  
  234. .ne 4
  235. .ti -5
  236. wildexp(&argc, &argv)
  237. .br 
  238. Expands ambiguous file names into a list of unambiguous file names.
  239. Wildexp() can be called before the call to dioinit() if desired.
  240.  
  241. You must initialize the variable _allocp to NULL before calling wildexp().
  242. Note that wildexp() uses sbrk() to obtain storage so don't go playing
  243. around with memory that is outside the external or stack areas unless
  244. you obtain the memory through sbrk() or alloc() calls.
  245. .br
  246. .in -5
  247.  
  248.  
  249. .ne 6
  250. .ti -7
  251. EXAMPLES
  252.  
  253. Multiple pipes may be chained on one command line.
  254. The following command feeds the output of program "foo" into the
  255. input of program "bar", the output of "bar" into the input of
  256. program "zot", and the output of "zot" into a file called "output":
  257.  
  258.     A>foo arg1 |bar |zot arg2 arg3 >output
  259.  
  260. "arg1" is an actual argument to "foo", and "arg2" and "arg3" are
  261. actual arguments to "zot". This illustrates how actual arguments
  262. may be interspersed with redirection commands. The programs see
  263. the actual arguments, but command line preprocessing handled by the
  264. "dioinit" function cause the programs to never need to know about
  265. the redirection commands. Note that all three programs ("foo", "bar"
  266. and "zot") must have been compiled and linked to use the "dio"
  267. package.
  268.  
  269. An afn preceded by a "!" causes all names matching the given
  270. afn to be EXCLUDED from the resulting expansion list.
  271. Thus, to yield a command line containing all files except
  272. "COM" files, you'd say:
  273.  
  274. .ce
  275. progname !*.com <cr>
  276.  
  277. To get all files on B: except .C files, say:
  278.  
  279. .ce
  280. prognam b:*.* !b:*.c <cr>
  281.  
  282.  
  283. .ne 6
  284. .ti -7
  285. FILES
  286.  
  287. .nf
  288. printer, tty (special files)
  289. tempin.$$$, tempout.$$$ (created for pipes)
  290. .fi
  291.  
  292.  
  293. .ne 6
  294. .ti -7
  295. SEE ALSO
  296.  
  297. file, rawfile and args on the Software Tools Disk
  298.  
  299.  
  300. .ne 6
  301. .ti -7
  302. DIAGNOSTICS
  303.  
  304. .in +5
  305. .br
  306. .ti -5
  307. "Can't open"
  308. .br
  309. The file whose name follows a '<' does not exist.
  310. .br
  311. .ti -5
  312. "Can't create"
  313. .br
  314. The file whose name follows a '>' or '@' could not
  315. be created.
  316. The disk is probably full.
  317. .br
  318. .ti -5
  319. "bad '<' redirection"
  320. .br
  321. A file name must follow a '<' on the command line.
  322. No intervening blanks are allowed.
  323. .br
  324. .ti -5
  325. "bad '@' redirection"
  326. .br
  327. A file name must follow a '@' on the command line.
  328. No intervening blanks are allowed.
  329. .br
  330. .ti -5
  331. "bad '>' redirection"
  332. .br
  333. A file name must follow a '>' on the command line.
  334. No intervening blanks are allowed.
  335. .br
  336. .ti -5
  337. "bad pipe specifier"
  338. .br
  339. The name of a program must follow a '|'.
  340. No intervening blanks are allowed.
  341.